home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / gnuish / ginf / configur.inf (.txt) < prev    next >
GNU Info File  |  1993-09-30  |  80KB  |  1,449 lines
  1. This is Info file configure.info, produced by Makeinfo-1.55 from the
  2. input file configure.texi.
  3. START-INFO-DIR-ENTRY
  4. * configure: (configure).        Cygnus configure.
  5. END-INFO-DIR-ENTRY
  6.    This document describes the Cygnus Support version of `configure'.
  7.    Copyright (C) 1991, 1992, 1993 Cygnus Support Permission is granted
  8. to make and distribute verbatim copies of this manual provided the
  9. copyright notice and this permission notice are preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided that
  12. the entire resulting derived work is distributed under the terms of a
  13. permission notice identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions, except that this permission notice may be stated in a
  17. translation approved by Cygnus Support.
  18. Indirect:
  19. configure.info-1: 966
  20. configure.info-2: 49913
  21. Tag Table:
  22. (Indirect)
  23. Node: Top
  24. Node: What configure does
  25. Node: Invoking configure
  26. Node: Using configure
  27. 11266
  28. Node: What configure really does
  29. 12621
  30. Node: Build variables
  31. 17895
  32. Node: Build directories
  33. 20077
  34. Node: Makefile generation
  35. 23481
  36. Node: config.guess
  37. 25012
  38. Node: config.status
  39. 25890
  40. Node: configure.in
  41. 26447
  42. Node: configure variables
  43. 28117
  44. Node: Minimal
  45. 36279
  46. Node: Declarations
  47. 37089
  48. Node: per-host
  49. 37563
  50. Node: per-target
  51. 38300
  52. Node: post-target
  53. 39123
  54. Node: Example
  55. 39706
  56. Node: Install locations
  57. 40413
  58. Node: prefix
  59. 41214
  60. Node: exec_prefix
  61. 42107
  62. Node: Install details
  63. 43912
  64. Node: Host
  65. 48849
  66. Node: Target
  67. 49477
  68. Node: Makefile fragments
  69. 49913
  70. Node: Makefile extensions
  71. 51525
  72. Node: Porting
  73. 55252
  74. Node: Programs
  75. 55704
  76. Node: Hosts and targets
  77. 60550
  78. Node: Sites
  79. 62213
  80. Node: Variables Index
  81. 62913
  82. Node: Concept Index
  83. 65905
  84. End Tag Table
  85. This is Info file configure.info, produced by Makeinfo-1.55 from the
  86. input file configure.texi.
  87. START-INFO-DIR-ENTRY
  88. * configure: (configure).        Cygnus configure.
  89. END-INFO-DIR-ENTRY
  90.    This document describes the Cygnus Support version of `configure'.
  91.    Copyright (C) 1991, 1992, 1993 Cygnus Support Permission is granted
  92. to make and distribute verbatim copies of this manual provided the
  93. copyright notice and this permission notice are preserved on all copies.
  94.    Permission is granted to copy and distribute modified versions of
  95. this manual under the conditions for verbatim copying, provided that
  96. the entire resulting derived work is distributed under the terms of a
  97. permission notice identical to this one.
  98.    Permission is granted to copy and distribute translations of this
  99. manual into another language, under the above conditions for modified
  100. versions, except that this permission notice may be stated in a
  101. translation approved by Cygnus Support.
  102. File: configure.info,  Node: Top,  Next: What configure does,  Prev: (DIR),  Up: (DIR)
  103. Cygnus configure
  104. ****************
  105.    This file documents the configuration system used and distributed by
  106. Cygnus Support.
  107. * Menu:
  108. * What configure does::    What configure does
  109. * Invoking configure::     Invoking configure--basic usage
  110. * Using configure::        More than you ever wanted to know
  111. * Porting::                How to use configure with new programs
  112. * Variables Index::
  113. * Concept Index::
  114. File: configure.info,  Node: What configure does,  Next: Invoking configure,  Prev: Top,  Up: Top
  115. What `configure' does
  116. *********************
  117.    This manual documents Cygnus `configure', a program which helps to
  118. automate much of the setup activity associated with building large
  119. suites of programs, such the Cygnus Support Developer's Kit.  This
  120. manual is therefore geared toward readers who are likely to face the
  121. problem of configuring software in source form before compiling and
  122. installing it.  We assume you are an experienced programmer or system
  123. administrator.  For further background on this topic, see *Note
  124. Apologia Configure: (cfg-paper)Some Basic Terms, by K. Richard Pixley.
  125.    When `configure' runs, it does the following things:
  126. ** creates build directories*
  127.      When you run `configure' with the `--srcdir' option, it uses the
  128.      current directory as the "build directory", creating under it a
  129.      directory tree that parallels the directory structure of the
  130.      source directory.  If you don't specify a `srcdir', `configure'
  131.      first assumes that the source code you wish to configure is in
  132.      your current directory; if it finds no `configure.in' input file
  133.      there, it searches in the directory `configure' itself lies in.
  134.      (For details, see *Note Build directories: Build directories.)
  135. ** generates `Makefile'*
  136.      A `Makefile' template from the source directory, usually called
  137.      `Makefile.in', is copied to an output file in the build directory
  138.      which is most often named `Makefile'.  `configure' places
  139.      definitions for a number of standard `Makefile' macros at the
  140.      beginning of the output file.  If `--prefix=DIR' or
  141.      `--exec_prefix=DIR' are specified on the `configure' command line,
  142.      corresponding `Makefile' variables are set accordingly.  If host,
  143.      target, or site-specific `Makefile' fragments exist, these are
  144.      inserted into the output file.  (For details, see *Note `Makefile'
  145.      generation: Makefile generation.)
  146. ** generates `.gdbinit'*
  147.      If the source directory contains a `.gdbinit' file and the build
  148.      directory is not the same as the source directory, a `.gdbinit'
  149.      file is created in the build directory.  This `.gdbinit' file
  150.      contains commands which allow the source directory to be read when
  151.      debugging with the GNU debugger, `gdb'.  (*Note Command Files:
  152.      (gdb)Command Files.)
  153. ** makes symbolic links*
  154.      Most build directories require that some symbolic links with
  155.      generic names are built pointing to specific files in the source
  156.      directory.  If the system where `configure' runs cannot support
  157.      symbolic links, hard links are used instead.  (For details, see
  158.      *Note The `configure.in' input file: configure.in.)
  159. ** generates `config.status'*
  160.      `configure' creates a shell script named `config.status' in the
  161.      build directory.  This shell script, when run from the build
  162.      directory (usually from within a `Makefile'), will reconfigure the
  163.      build directory (but not its subdirectories).  This is most often
  164.      used to have a `Makefile' update itself automatically if a new
  165.      source directory is available.
  166. ** calls itself recursively*
  167.      If the source directory has subdirectories that should also be
  168.      configured, `configure' is called for each.
  169. File: configure.info,  Node: Invoking configure,  Next: Using configure,  Prev: What configure does,  Up: Top
  170. Invoking `configure'
  171. ********************
  172.    Cygnus `configure' is a shell script which resides in a source tree.
  173. The usual way to invoke `configure' is from the shell, as follows:
  174.      eg$ ./configure HOST
  175. This prepares the source in the current directory (`.') to be compiled
  176. for a HOST environment.  It assumes that you wish to build programs and
  177. files in the default "build directory" (also the current directory,
  178. `.').  If you neglect to specify a value for HOST, Cygnus `configure'
  179. will attempt to discover this information by itself (*note Determining
  180. system information: config.guess.).  For information on HOST
  181. environments, *Note Host: Host.
  182.    All GNU software is packaged with one or more `configure' script(s)
  183. (*note How Configuration Should Work: (standards)Configuration.).  By
  184. using `configure' you prepare the source for your specific environment
  185. by selecting and using `Makefile' fragments and fragments of shell
  186. scripts, which are prepared in advance and stored with the source.
  187.    `configure''s command-line options also allow you to specify other
  188. aspects of the source configuration:
  189.        configure HOST  [--target=TARGET] [--srcdir=DIR] [--rm]
  190.                  [--site=SITE] [--prefix=DIR] [--exec_prefix=DIR]
  191.                  [--program_prefix=STRING] [--tmpdir=DIR]
  192.                  [--with-PACKAGE[=YES/NO]] [--norecursion]
  193.                  [--nfp] [-s] [-v] [-V | --version] [--help]
  194. `--target=TARGET'
  195.      Requests that the sources be configured to target the TARGET
  196.      machine.  If no target is specified explicitly, the target is
  197.      assumed to be the same as the host (i.e., a "native"
  198.      configuration).  *Note Host: Host, and *Note Target: Target, for
  199.      discussions of each.
  200. `--srcdir=DIR'
  201.      Direct each generated `Makefile' to use the sources located in
  202.      directory DIR.  Use this option whenever you wish the object code
  203.      to reside in a different place from the source code.  The "build
  204.      directory" is always assumed to be the directory you call
  205.      `configure' from.  See *Note Build directories: Build directories,
  206.      for an example.  If the source directory is not specified,
  207.      `configure' assumes that the source is in your current directory.
  208.      If `configure' finds no `configure.in' there, it searches in the
  209.      same directory that the `configure' script itself lies in.
  210.      Pathnames specified (Values for DIR) can be either absolute
  211.      relative to the *build* directory.
  212. `--rm'
  213.      *Remove* the configuration specified by HOST and the other
  214.      command-line options, rather than create it.
  215. `--site=SITE'
  216.      Generate the `Makefile' using site-specific `Makefile' fragments
  217.      for SITE.  *Note Adding information about local conventions:
  218.      Makefile fragments.
  219. `--prefix=DIR'
  220.      Configure the source to install programs and files under directory
  221.      DIR.
  222.      This option sets the variable `prefix'.  Each generated `Makefile'
  223.      will have its `prefix' variables set to this value.  (*Note What
  224.      `configure' really does: What configure really does.)
  225. `--exec_prefix=DIR'
  226.      Configure the source to install "host dependent" files in DIR.
  227.      This option sets the variable `exec_prefix'.  Each generated
  228.      `Makefile' will have its `exec_prefix' variables set to this value.
  229.      (*Note What `configure' really does: What configure really does.)
  230. `--program_prefix=STRING'
  231.      Configure the source to install certain programs using STRING as a
  232.      prefix.  This applies to programs which might be used for
  233.      cross-compilation, such as the compiler and the binary utilities,
  234.      and also to programs which have the same names as common Unix
  235.      programs, such as `make'.
  236.      This option sets the variable `program_prefix'.  Each generated
  237.      `Makefile' will have its `program_prefix' variables set to this
  238.      value.  (*Note What `configure' really does: What configure really
  239.      does.)
  240. `--tmpdir=TMPDIR'
  241.      Use the directory TMPDIR for `configure''s temporary files.  The
  242.      default is the value of the environment variable `TMPDIR', or
  243.      `/tmp' if the environment variable is not set.
  244. `--with-PACKAGE[=YES/NO]'
  245.      Set a flag for the compiler to recognize that PACKAGE is explicitly
  246.      present, or not present, depending on YES/NO.  If YES/NO is
  247.      nonexistent, its value is assumed to be "yes".
  248.      For example, if you wish to configure the program `gcc' for a Sun
  249.      SPARCstation running SunOS 4.x, and you want to make sure `gcc' is
  250.      built using the GNU linker `ld', you can configure using
  251.           eg$ configure --with-gnu-ld sun4
  252.      *Note What `configure' really does: What configure really does, for
  253.      details.  See the installation or release notes for your
  254.      particular package for details on which other PACKAGE flags are
  255.      useful.
  256. `--norecursion'
  257.      Configure only this directory; ignore any subdirectories.  This is
  258.      used by the executable shell script `config.status' to reconfigure
  259.      only the current directory; it is most often used
  260.      non-interactively, when `make' is invoked.  (*Note
  261.      `config.status': config.status.)
  262. `--nfp'
  263.      Explicitly assume that the intended HOST has no floating point
  264.      unit.
  265.      This option is used internally by `configure' when calling itself
  266.      recursively in subdirectories.  Its sole purpose is to suppress
  267.      status output.  You can override this effect with the `--verbose'
  268.      option.
  269.      Print status lines for each directory configured.  Normally, only
  270.      the status lines for the initial working directory are printed.
  271. `--version'
  272.      Print `configure' version number.
  273. `--help'
  274.      Display a quick summary of how to invoke `configure'.
  275.    *Note:* You may introduce options with a single dash, `-', rather
  276. than two dashes, `--'.  However, you may not be able to truncate long
  277. option names when using a single dash.  When using two dashes, options
  278. may be abbreviated as long as each option can be uniquely identified.
  279. For example,
  280.      eg$ configure --s=/u/me/src myhost
  281. is ambiguous, as `--s' could refer to either `--site' or `--srcdir'.
  282. However,
  283.      eg$ configure --src=/u/me/src myhost
  284. is a perfectly legal abbreviation.  (Note that the above will probably
  285. not work unless there exists a valid host called `myhost' and you have
  286. source code in the directory `/u/me/src' that you wish to configure.)
  287. File: configure.info,  Node: Using configure,  Next: Porting,  Prev: Invoking configure,  Up: Top
  288. Using `configure'
  289. *****************
  290.    `configure' prepares source directories for the process of building
  291. working programs.  "Configuring" is the process of preparing software to
  292. compile correctly on a given "host", optionally for a given "target".
  293. A program cannot be built until its source has been configured.
  294.    `configure' subsequently writes a configured `Makefile' from a
  295. pre-built template; `configure' uses variables that have been set in the
  296. configuring process to determine the values of some variables in the
  297. `Makefile'.  Because of this we will refer to both `configure'
  298. variables and `Makefile' variables.  This convention allows us to
  299. determine where the variable should be set initially, in either
  300. `configure.in' or `Makefile.in'.
  301. * Menu:
  302. * What configure really does:: What configure really does
  303. * configure.in::               The configure.in input file
  304. * Install locations::          Where to install things once they are built
  305. * Host::                       Telling configure what will source will be built
  306. * Target::                     Telling configure what the source will target
  307. * Makefile fragments::         Adding information about local conventions
  308. * Makefile extensions::        Extensions to the GNU coding standards
  309. File: configure.info,  Node: What configure really does,  Next: configure.in,  Up: Using configure
  310. What `configure' really does
  311. ============================
  312.    Cygnus `configure' is a complex shell script you use to set up a
  313. certain environment in which your programs will compile correctly for
  314. your machine and operating system, and will install themselves in
  315. proper places.  `configure' accomplishes this task in a variety of ways:
  316.    * it generates a `Makefile' from a custom template called
  317.      `Makefile.in' in each relevant source directory;
  318.    * you set certain variables for `configure', either on the command
  319.      line or in the file `configure.in', which subsequently sets
  320.      variables in each generated `Makefile' to be used by `make' when
  321.      actually building the software;
  322.    * it establishes and populates "build directories", places for your
  323.      compiled code to reside before being installed;
  324.    * it generates a `.gdbinit' in the build directory, if needed, to
  325.      communicate information to `gdb';
  326.    * it generates a shell script called `config.status' which is used
  327.      most often by the `Makefile' to reconfigure itself.
  328.    * it recurs in subdirectories, setting up entire trees so that they
  329.      build correctly; if `configure' finds another `configure' script
  330.      further down in a given source tree, it knows to use this script
  331.      and not recur.
  332.    For the sake of safety (i.e., in order to prevent broken
  333. installations), the GNU coding standards call for software to be
  334. "configured" in such a way that an end user trying to build a given
  335. package will be able to do so by affecting a finite number of
  336. variables.  All GNU software comes with an executable `configure' shell
  337. script which sets up an environment within a build directory which will
  338. correctly compile your new package for your host (or, alternatively,
  339. whatever host you specify to `configure').  For further background on
  340. this topic, see *Note Apologia Configure: (cfg-paper)Some Basic Terms,
  341. by K. Richard Pixley.
  342.    Use `configure' to effectively communicate with the build process:
  343.    * correct terms for certain variables;
  344.    * what host you wish to configure a given package for (*note Host:
  345.      Host.);
  346.    * to tell the build tools where you want this package installed (by
  347.      using `prefix', `exec_prefix' and `program_prefix'; *note Full
  348.      descriptions of all installation directories: Install details.);
  349.    * optionally, what machine you wish to "target" this package's output
  350.      to (*note Target: Target.);
  351.    * what other GNU packages are already installed and available to this
  352.      particular build (by using the `--with-PACKAGE' option; *note
  353.      Invoking `configure': Invoking configure.);
  354.    * where to build temporary files (by using the `--tmpdir=DIR'
  355.      option; *note Invoking `configure': Invoking configure.);
  356.    * whether to recur in subdirectories (changeable through the
  357.      `--norecursion' option; *note Invoking `configure': Invoking
  358.      configure.).
  359.    `configure' uses a few other files to complete its tasks.  These are
  360. discussed in detail where noted.
  361. `configure.in'
  362.      Input file for `configure'.  Shell script fragments reside here.
  363.      *Note The `configure.in' input file: configure.in.
  364. `Makefile.in'
  365.      Template which `configure' uses to build a file called `Makefile'
  366.      in the "build directory".  *Note `Makefile' generation: Makefile
  367.      generation.
  368. `config.sub'
  369.      Shell script used by `configure' to expand referents to the HOST
  370.      argument into a single specification of the form CPU-VENDOR-OS.
  371.      For instance, on the command line you would specify
  372.           eg$ ./configure sun4
  373.      to configure for a Sun SPARCstation running SunOS 4.x.  `configure'
  374.      consults `config.sub' to find that the three-part specification
  375.      for this is
  376.           sparc-sun-sunos4.1.1
  377.      which notes the CPU as `sparc', the MANUFACTURER as `sun' (Sun
  378.      Microsystems), and the OS (operating system) as `sunos4.1.1', the
  379.      SunOS 4.1.1 release.  *Note Variables available to `configure':
  380.      configure variables.
  381. `config.guess'
  382.      If you neglect to put the HOST argument on the command line,
  383.      `configure' uses `config.guess' to make an analysis of your machine
  384.      (and, incidentally, assumes that you wish to configure your
  385.      software for the machine you happen to be running on).  The output
  386.      of `config.guess' is the same three-part identifier as described
  387.      above.
  388. `config.status'
  389.      The final step in configuring a directory is to create an
  390.      executable shell script, `config.status'.  The main purpose of
  391.      this file is to allow the `Makefile' for the current directory to
  392.      rebuild itself, if necessary.  *Note `config.status':
  393.      config.status.
  394. `config/*'
  395.      `configure' uses three types of `Makefile' "fragments", which
  396.      reside in the directory `SRCDIR/config/'.  *Note Adding
  397.      information about local conventions: Makefile fragments.
  398. * Menu:
  399. * Build variables::         Variable-spaghetti made simple
  400. * Build directories::       Build directories described well
  401. * Makefile generation::     To build a Makefile
  402. * config.guess::            Be vewwy quiet, I'm hunting system information
  403. * config.status::           To rebuild a Makefile
  404. File: configure.info,  Node: Build variables,  Next: Build directories,  Up: What configure really does
  405. Build variables
  406. ---------------
  407.    There are several variables in the build process which you can
  408. control through build programs such as `make'.  These include machine
  409. definitions, local conventions, installation locations, locations for
  410. temporary files, etc.  This data is accessible through certain
  411. variables which are configurable in the build process; we can refer to
  412. them as "build variables".
  413.    For lists of build variables which you can affect by using
  414. `configure', see *Note Variables available to `configure.in': configure
  415. variables, and *Note Full descriptions of all installation directories:
  416. Install details.
  417.    Generally, build variables, which are used by the `Makefile' to
  418. determine various aspects of the build and installation processes, are
  419. changeable by command-line options to `configure'.  The sense in this
  420. is especially seen when building large suites of programs, like the
  421. Cygnus Support Developer's Kit, whose individual programs reside in
  422. several subdirectories of a single source code "tree".  All of these
  423. subdirectories need to be configured with information relative to the
  424. "build directory", which is not known until `configure' is run.  Unless
  425. specified otherwise, `configure' recursively configures every
  426. subdirectory in the source tree with correct information (i.e.,
  427. supplied information that is correct, as well as correctly supplied
  428. information).
  429.    Build variables are passed from `configure' directly into the
  430. `Makefile', and use the same names.  In other words, if you specify
  431.      eg$ ./configure --prefix=/usr/gnu/local ... HOST
  432. on the command line, `configure' sets an variable called `prefix' to
  433. `/usr/gnu/local', and passes this into the `Makefile' in the same
  434. manner.  After this command, each `Makefile' generated by `configure'
  435. will contain a line that reads:
  436.      prefix = /usr/gnu/local
  437.    For a list of the `Makefile' variables `configure' can change, and
  438. instructions on how to change them, see *Note Variables available to
  439. `configure.in': configure variables, and *Note Invoking `configure':
  440. Invoking configure.
  441. File: configure.info,  Node: Build directories,  Next: Makefile generation,  Prev: Build variables,  Up: What configure really does
  442. Build directories
  443. -----------------
  444.    By default, `configure' builds a `Makefile' and symbolic links in the
  445. same directory as the source files.  This default works for many cases,
  446. but it has limitations.  For instance, using this approach, you can
  447. only build object code for one host at a time.
  448.    We refer to each directory where `configure' builds a `Makefile' as
  449. a "build directory".
  450.    The build directory for any given build is always the directory from
  451. which you call `configure', or `.' relative to your prompt.  The default
  452. "source directory", the place `configure' looks to find source code, is
  453. also `.'.  For instance, if we have a directory `/gnu-stuff/src/' that
  454. is the top branch of a tree of GNU source code we wish to configure,
  455. then the program we will use to configure this code is
  456. `/gnu-stuff/src/configure', as follows.  (Assume for the sake of
  457. argument that our machine is a sun4.)
  458.      eg$ cd /gnu-stuff/src
  459.      eg$ ./configure sun4
  460.      Created "Makefile" in /gnu-stuff/src
  461.      eg$
  462.    We just configured the code in `/gnu-stuff/src' to run on a Sun
  463. SPARCstation using SunOS 4.x by creating a `Makefile' in
  464. `/gnu-stuff/src'.  By default, we also specified that when this code is
  465. built, the object code should reside in the same directory,
  466. `/gnu-stuff/src'.
  467.    However, if we wanted to build this code for more than one host, we
  468. would be in trouble, because the new configuration would write over the
  469. old one, destroying it in the process.  What we can do is to make a new
  470. "build directory" and configure from there.  Running `configure' from
  471. the new directory will place a correct `Makefile' and a `config.status'
  472. in this new file.  That is all `configure' does; we must run `make' to
  473. generate any object code.
  474.    The new `Makefile' in `/gnu-stuff/sun4-obj', created from the
  475. template file `/gnu-stuff/src/Makefile.in', contains all the information
  476. needed to build the program.
  477.      eg$ mkdir /gnu-stuff/sun4-obj
  478.      eg$ cd /gnu-stuff/sun4-obj
  479.      eg$ ../src/configure --srcdir=../src sun4
  480.      Created "Makefile" in /gnu-stuff/sun4-obj
  481.      eg$ ls
  482.      Makefile       config.status
  483.      eg$ make all info install install-info clean
  484.      COMPILATION MESSAGES...
  485.      eg$ mkdir /gnu-stuff/solaris2
  486.      eg$ cd /gnu-stuff/solaris2
  487.      eg$ ../src/configure --srcdir=../src sol2
  488.      Created "Makefile" in /gnu-stuff/solaris2
  489.      eg$ ls
  490.      Makefile       config.status
  491.      eg$ make all info install install-info clean
  492.      COMPILATION MESSAGES...
  493.    We can repeat this for other configurations of the same software
  494. simply by making a new build directory and reconfiguring from inside
  495. it.  If you neglect to specify the "host" argument, `configure' will
  496. attempt to figure out what kind of machine and operating system you
  497. happen to be using.  *Note Determining system information:
  498. config.guess.  Of course, this may not always be the configuration you
  499. wish to build.
  500.    *Caution:* If you build more than one configuration for a single
  501. program, remember that you must also specify a different `--prefix' for
  502. each configuration at configure-time.  Otherwise, both configurations
  503. will be installed in the same default location (`/usr/local'); the
  504. configuration to be installed last would overwrite previously installed
  505. configurations.
  506. File: configure.info,  Node: Makefile generation,  Next: config.guess,  Prev: Build directories,  Up: What configure really does
  507. `Makefile' generation
  508. ---------------------
  509.    Cygnus `configure' creates a file called `Makefile' in the build
  510. directory which can be used with `make' to automatically build a given
  511. program or package.  `configure' also builds a `Makefile' for each
  512. relevant subdirectory for a given program or package (irrelevant
  513. subdirectories would be those which contain no code which needs
  514. configuring, and which therefore have no `configure' input file
  515. `configure.in' and no `Makefile' template `Makefile.in').  *Note `make'
  516. Invocation: (make)Running, for details on using `make' to compile your
  517. source code.
  518.    Each `Makefile' contains variables which have been configured for a
  519. specific build.  These build variables are determined when `configure'
  520. is run.  All build variables have defaults.  By default, `configure'
  521. generates a `Makefile' which specifies:
  522.    * a "native" build, which is to occur
  523.    * in the current directory, and which will be installed
  524.    * in the default installation directory (`/usr/local') when the code
  525.      is compiled with `make'.
  526. Variables are changeable through command-line options to `configure'
  527. (*note Invoking `configure': Invoking configure.).
  528.    If you are porting a new program and intend to use `configure', see
  529. *Note Porting with `configure': Porting, as well as *Note Writing
  530. Makefiles: (make)Makefiles, and *Note Makefile Conventions:
  531. (standards)Makefiles.
  532. File: configure.info,  Node: config.guess,  Next: config.status,  Prev: Makefile generation,  Up: What configure really does
  533. Determining system information
  534. ------------------------------
  535.    The shell script `config.guess' is called when you do not specify a
  536. HOST on the command line to `configure'.  `config.guess' acquires
  537. available system information from your local machine through the shell
  538. command `uname'.  It compares this information to a database and
  539. attempts to determine a usable three-part system identifier (known as a
  540. "triple") to use as your HOST.  *Note What `configure' really does:
  541. What configure really does, to see how this information is used.
  542.    *Note:*  If you do not specify a HOST on the command line,
  543. `configure' will attempt to configure your software to run on the
  544. machine you happen to be using.  This may not be the configuration you
  545. desire.
  546. File: configure.info,  Node: config.status,  Prev: config.guess,  Up: What configure really does
  547. `config.status'
  548. ---------------
  549.    The final step in configuring a directory is to create an executable
  550. shell script, `config.status'.  The main purpose of this file is to
  551. allow the `Makefile' for the current directory to rebuild itself, if
  552. necessary.  It is usually run from within the `Makefile'.  *Note
  553. Extensions to the GNU coding standards: Makefile extensions.
  554.    `config.status' also contains a record of the `configure' session
  555. which created it.
  556. File: configure.info,  Node: configure.in,  Next: Install locations,  Prev: What configure really does,  Up: Using configure
  557. The `configure.in' input file
  558. =============================
  559.    A `configure.in' file for Cygnus `configure' consists of a
  560. "per-invocation" section, followed by a "per-host" section, followed by
  561. a "per-target" section, optionally followed by a "post-target" section.
  562. Each section is a shell script fragment, which is executed by the
  563. `configure' shell script at an appropriate time.  Values are passed
  564. among `configure' and the shell fragments through a set of shell
  565. variables.  When each section is being interpreted by the shell, the
  566. shell's current directory is the build directory, and any files created
  567. by the section (or referred to by the section) will be relative to the
  568. build directory.  To reference files in other places (such as the
  569. source directory), prepend a shell variable such as `$(srcdir)/' to the
  570. desired file name.
  571.    The beginning of the `configure.in' file begins the "per-invocation"
  572. section.
  573.    A line beginning with `# per-host:' begins the "per-host" section.
  574.    A line beginning with `# per-target:' begins the "per-target"
  575. section.
  576.    If it exists, the "post-target" section begins with `# post-target:'.
  577. * Menu:
  578. * configure variables::    Variables available to configure.in
  579. * Minimal::                A minimal configure.in
  580. * Declarations::           For each invocation
  581. * per-host::               Host-specific instructions
  582. * per-target::             Target-specific instructions
  583. * post-target::            Instructions to be executed after target info
  584. * Example::                An example configure.in
  585. File: configure.info,  Node: configure variables,  Next: Minimal,  Up: configure.in
  586. Variables available to `configure.in'
  587. -------------------------------------
  588.    The following variables pass information between the standard parts
  589. of `configure' and the shell-script fragments in `configure.in':
  590. `srctrigger'
  591.      Contains the name of a source file that is expected to live in the
  592.      source directory.  You must usually set this in the
  593.      "per-invocation" section of `configure.in'.  `configure' tests to
  594.      see that this file exists.  If the file does not exist,
  595.      `configure' prints an error message.  This is used as a sanity
  596.      check that `configure.in' matches the source directory.
  597. `srcname'
  598.      Contains the name of the source collection contained in the source
  599.      directory.  You must usually set this in the "per-invocation"
  600.      section of `configure.in'.  If the file named in `srctrigger' does
  601.      not exist, `configure' uses the value of `srcname' when it prints
  602.      the error message.
  603. `configdirs'
  604.      Contains the names of any subdirectories in which `configure'
  605.      should recurse.  You must usually set this in the "per-invocation"
  606.      section of `configure.in'.  If `Makefile.in' contains a line
  607.      starting with `SUBDIRS =', then it will be replaced with an
  608.      assignment to `SUBDIRS' using the value of `configdirs' (if
  609.      `subdirs' is empty).  This can be used to determine which
  610.      directories to configure and build depending on the host and
  611.      target configurations.  Use `configdirs' (instead of the `subdirs'
  612.      variable described below) if you want to be able to partition the
  613.      subdirectories, or use independent `Makefile' fragments.  Each
  614.      subdirectory can be independent, and independently reconfigured.
  615. `subdirs'
  616.      Contains the names of any subdirectories where `configure' should
  617.      create a `Makefile' (in addition to the current directory),
  618.      *without* recursively running `configure'.  Use `subdirs' (instead
  619.      of the `configdirs' variable described above) if you want to
  620.      configure all of the directories as a unit.  Since there is a
  621.      single invocation of `configure' that configures many directories,
  622.      all the directories can use the same `Makefile' fragments, and the
  623.      same `configure.in'.
  624. `host'
  625.      Contains the full configuration name for the host (generated by
  626.      the script `config.sub' from the name that you entered).  This is
  627.      a three-part name (commonly referred to as a "triple") of the form
  628.      CPU-VENDOR-OS.
  629.      There are separate variables `host_cpu', `host_vendor', and
  630.      `host_os' that you can use to test each of the three parts; this
  631.      variable is useful, however, for error messages, and for testing
  632.      combinations of the three components.
  633. `host_cpu'
  634.      Contains the first element of the canonical triple representing
  635.      the host as returned by `config.sub'.  This is occasionally used to
  636.      distinguish between minor variations of a particular vendor's
  637.      operating system and sometimes to determine variations in binary
  638.      format between the host and the target.
  639. `host_vendor'
  640.      Contains the second element of the canonical triple representing
  641.      the host as returned by `config.sub'.  This is usually used to
  642.      distinguish among the numerous variations of *common* operating
  643.      systems.
  644. `host_os'
  645.      Contains the the third element of the canonical triple
  646.      representing the host as returned by `config.sub'.
  647. `target'
  648.      Contains the full configuration name (generated by the script
  649.      `config.sub' from the name that you entered) for the target.  Like
  650.      the host, this is a three-part name of the form CPU-VENDOR-OS.
  651.      There are separate variables `target_cpu', `target_vendor', and
  652.      `target_os' that you can use to test each of the three parts; this
  653.      variable is useful, however, for error messages, and for testing
  654.      combinations of the three components.
  655. `target_cpu'
  656.      Contains the first element of the canonical triple representing
  657.      the target as returned by `config.sub'.  This variable is used
  658.      heavily by programs which are involved in building other programs,
  659.      like the compiler, assembler, linker, etc.  Most programs will not
  660.      need the `target' variables at all, but this one could conceivably
  661.      be used to build a program, for instance, that operated on binary
  662.      data files whose byte order or alignment differ from the system
  663.      where the program is running.
  664. `target_vendor'
  665.      Contains the second element of the canonical triple representing
  666.      the target as returned by `config.sub'.  This is usually used to
  667.      distinguish among the numerous variations of *common* operating
  668.      systems or object file formats.  It is sometimes used to switch
  669.      between different flavors of user interfaces.
  670. `target_os'
  671.      Contains the the third element of the canonical triple
  672.      representing the target as returned by `config.sub'.  This
  673.      variable is used by development tools to distinguish between
  674.      subtle variations in object file formats that some vendors use
  675.      across operating system releases.  It might also be use to decide
  676.      which libraries to build or what user interface the tool should
  677.      provide.
  678. `floating_point'
  679.      Set to `no' if you invoked `configure' with the `--nfp'
  680.      command-line option, otherwise it is empty.  This is a request to
  681.      target machines with "no floating point" unit, even if the targets
  682.      ordinarily have floating point units available.
  683. `gas'
  684.      Set to `true' if you invoked `configure' with the `--with-gnu-as'
  685.      command line option, otherwise it is empty.  This is a request to
  686.      assume that the specified HOST machine has GNU `as' available even
  687.      if it ordinarily does not.
  688. `srcdir'
  689.      Set to the name of the directory containing the source for this
  690.      program.  This will be different from `.' if you have specified the
  691.      `--srcdir=DIR' option.  `srcdir' can indicate either an absolute
  692.      path or a path relative to the build directory.
  693. `package_makefile_frag'
  694.      If set in `configure.in', this variable should be the name a file
  695.      relative to `srcdir' to be included in the resulting `Makefile'.
  696.      If the named file does not exist, `configure' will print a warning
  697.      message.  This variable is not set by `configure'.
  698. `host_makefile_frag'
  699.      If set in `configure.in', this variable should be the name a file
  700.      relative to `srcdir' to be included in the resulting `Makefile'.
  701.      If the named file does not exist, `configure' will print a warning
  702.      message.  This variable is not set by `configure'.
  703. `target_makefile_frag'
  704.      If set in `configure.in', this variable should be the name of a
  705.      file, relative to `srcdir', to be included in the resulting
  706.      `Makefile'.  If the named file does not exist, `configure' will
  707.      print a warning message.  This variable is not set by `configure'.
  708. `site_makefile_frag'
  709.      Set to a file name representing to the default `Makefile' fragment
  710.      for this host.  It may be set in `configure.in' to override this
  711.      default.  Normally `site_makefile_frag' is empty, but will have a
  712.      value if you specify `--site=SITE' on the command line.
  713. `Makefile'
  714.      Set to the name of the generated `Makefile'.  Normally this value
  715.      is precisely `Makefile', but some programs may want something else.
  716. `removing'
  717.      Normally empty but will be set to some non-null value if you
  718.      specified `--rm' on the command line.  That is, if `removing' is
  719.      not empty, then `configure' is *removing* a configuration rather
  720.      than creating one.
  721. `files'
  722.      If this variable is not empty following the "per-target" section,
  723.      then each word in its value will be the target of a symbolic link
  724.      named in the corresponding word from the `links' variable.
  725. `links'
  726.      If the `files' variable is not empty following the "per-target"
  727.      section, then `configure' creates symbolic links with the first
  728.      word of `links' pointing to the first word of `files', the second
  729.      word of `links' pointing to the second word of `files', and so on.
  730. File: configure.info,  Node: Minimal,  Next: Declarations,  Prev: configure variables,  Up: configure.in
  731. A minimal `configure.in'
  732. ------------------------
  733.    A minimal `configure.in' consists of four lines.
  734.      srctrigger=foo.c
  735.      srcname="source for the foo program"
  736.      # per-host:
  737.      # per-target:
  738.    The `# per-host:' and `# per-target:' lines divide the file into the
  739. three required sections.  The `srctrigger' line names a file.
  740. `configure' checks to see that this file exists in the source directory
  741. before configuring.  If the `srctrigger' file does not exist,
  742. `configure' uses the value of `srcname' to print an error message about
  743. not finding the source.
  744.    This particular example uses no links, and only the default host,
  745. target, and site-specific `Makefile' fragments if they exist.
  746. File: configure.info,  Node: Declarations,  Next: per-host,  Prev: Minimal,  Up: configure.in
  747. For each invocation
  748. -------------------
  749.    `configure' invokes the entire shell script fragment from the start
  750. of `configure.in' up to a line beginning with `# per-host:' immediately
  751. after parsing command line arguments.  The variables `srctrigger' and
  752. `srcname' *must* be set here.
  753.    You might also want to set the variables `configdirs' and
  754. `package_makefile_frag' here.
  755. File: configure.info,  Node: per-host,  Next: per-target,  Prev: Declarations,  Up: configure.in
  756. Host-specific instructions
  757. --------------------------
  758.    The "per-host" section of `configure.in' starts with the line that
  759. begins with `# per-host:' and ends before a line beginning with
  760. `# per-target:'.  `configure' invokes the commands in the "per-host"
  761. section when determining host-specific information.
  762.    This section usually contains a big `case' statement using the
  763. variable `host' to determine appropriate values for
  764. `host_makefile_frag' and `files', although `files' is not usually set
  765. here.  Usually, it is set at the end of the "per-target" section after
  766. determining the names of the target specific configuration files.
  767. File: configure.info,  Node: per-target,  Next: post-target,  Prev: per-host,  Up: configure.in
  768. Target-specific instructions
  769. ----------------------------
  770.    The "per-target" section of `configure.in' starts with the line that
  771. begins with `# per-target:' and ends before the line that begins with
  772. `# post-target:', if there is such a line.  Otherwise the "per-target"
  773. section extends to the end of the file.  `configure' invokes the
  774. commands in the "per-target" section when determining target-specific
  775. information, and before building any files, directories, or links.
  776.    This section usually contains a big `case' statement using the
  777. variable `target' to determine appropriate values for
  778. `target_makefile_frag' and `files'.  The last lines in the "per-target"
  779. section normally set the variables `files' and `links'.
  780. File: configure.info,  Node: post-target,  Next: Example,  Prev: per-target,  Up: configure.in
  781. Instructions to be executed after target info
  782. ---------------------------------------------
  783.    The "post-target" section is optional.  If it exists, the
  784. `post-target' section starts with a line beginning with
  785. `# Post-target:' and extends to the end of the file.  If it exists,
  786. `configure' invokes this section once for each target after building
  787. all files, directories, or links.
  788.    This section is seldom needed, but you can use it to edit the
  789. `Makefile' generated by `configure'.
  790. File: configure.info,  Node: Example,  Prev: post-target,  Up: configure.in
  791. An example `configure.in'
  792. -------------------------
  793.    Here is a small example of a `configure.in' file.
  794.      # This file is a collection of shell script fragments
  795.      # used to tailor a template configure script as
  796.      # appropriate for this directory.  For more information,
  797.      # see configure.texi.
  798.      
  799.      configdirs=
  800.      srctrigger=warshall.c
  801.      srcname="bison"
  802.      
  803.      # per-host:
  804.      case "${host}" in
  805.      m88k-motorola-*)
  806.              host_makefile_frag=config/mh-delta88
  807.              ;;
  808.      esac
  809.      
  810.      # per-target:
  811.      files="bison_in.hairy"
  812.      links="bison.hairy"
  813.      
  814.      # post-target:
  815. File: configure.info,  Node: Install locations,  Next: Host,  Prev: configure.in,  Up: Using configure
  816. Install locations
  817. =================
  818.    Using the default configuration, `make install' creates a single
  819. tree of files, some of which are programs.  The location of this tree
  820. is determined by the value of the variable `prefix'.  The default value
  821. of `prefix' is `/usr/local'.  This is often correct for native tools
  822. installed on only one host.
  823. * Menu:
  824. * prefix::            Changing the default install directory
  825. * exec_prefix::       How to separate host independent files
  826.                                          from host dependent files when
  827.                                          installing for multiple hosts
  828. * Install details::   Full descriptions of all installation subdirectories
  829. File: configure.info,  Node: prefix,  Next: exec_prefix,  Up: Install locations
  830. Changing the default install directory
  831. --------------------------------------
  832.    In the default configuration, all files are installed in
  833. subdirectories of `/usr/local'.  The location is determined by the
  834. value of the `configure' variable `prefix'; in turn, this determines the
  835. value of the `Makefile' variable of the same name (`prefix').
  836.    You can also set the value of the `Makefile' variable `prefix'
  837. explicitly each time you invoke `make' if you are so inclined.  However,
  838. because many programs have this location compiled in, you must specify
  839. the `prefix' value consistently on each invocation of `make', or you
  840. will end up with a broken installation.
  841.    To make this easier, the value of the `configure' variable `prefix'
  842. can be set on the command line to `configure' using the option
  843. `--prefix='.
  844. File: configure.info,  Node: exec_prefix,  Next: Install details,  Prev: prefix,  Up: Install locations
  845. Installing for multiple hosts
  846. -----------------------------
  847.    By default, host dependent files are installed in subdirectories of
  848. `$(exec_prefix)'.  The location is determined by the value of the
  849. `configure' variable `exec_prefix', which determines the value of the
  850. `Makefile' variable `exec_prefix'.  This makes it easier to install for
  851. a single host, and simplifies changing the default location for the
  852. install tree.  The default doesn't allow for multiple hosts to
  853. effectively share host independent files, however.
  854.    To configure so that multiple hosts can share common files, use
  855. something like:
  856.      configure HOST1 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
  857.      make all info install install-info clean
  858.      
  859.      configure HOST2 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
  860.      make all info install install-info
  861.    The first line configures the source for HOST1 to place host-specific
  862. programs in subdirectories of `/usr/gnu/H-HOST1'.
  863.    The second line builds and installs all programs for HOST1,
  864. including both host-independent and host-specific files, as well as
  865. removing the host-specific object files from of the build directory.
  866.    The third line reconfigures the source for HOST2 to place host
  867. specific programs in subdirectories of `/usr/gnu/H-HOST2'.
  868.    The fourth line builds and installs all programs for HOST2.  Host
  869. specific files are installed in new directories, but the host
  870. independent files are installed *on top of* the host independent files
  871. installed for HOST1.  This results in a single copy of the host
  872. independent files, suitable for use by both hosts.
  873.    *Note Extensions to the GNU coding standards: Makefile extensions,
  874. for more information.
  875. File: configure.info,  Node: Install details,  Prev: exec_prefix,  Up: Install locations
  876. Full descriptions of all installation subdirectories
  877. ----------------------------------------------------
  878.    During any install, a number of standard directories are created.
  879. Their names are determined by `Makefile' variables.  Some of the
  880. defaults for `Makefile' variables can be changed at configuration time
  881. using command line options to `configure'.  For more information on the
  882. standard directories or the `Makefile' variables, please refer to *Note
  883. Makefile Conventions: (standards)Makefiles.  See also *Note Extensions
  884. to the GNU coding standards: Makefile extensions.
  885.    Note that `configure' does not create the directory indicated by the
  886. variable `srcdir' at any time.  `$(srcdir)' is not an installation
  887. directory.
  888.    You can override all `Makefile' variables on the command line to
  889. `make'.  (*Note Overriding Variables: (make)Overriding.)  If you do so,
  890. you will need to specify the value precisely the same way for each
  891. invocation of `make', or you risk ending up with a broken installation.
  892. This is because many programs have the locations of other programs or
  893. files compiled into them.  If you find yourself overriding any of the
  894. variables frequently, you should consider site dependent `Makefile'
  895. fragments.  See also *Note Adding site info: Sites.
  896.    During `make install', a number of standard directories are created
  897. and populated.  The following `Makefile' variables define them.  Those
  898. whose defaults are set by corresponding `configure' variables are marked
  899. "`Makefile' and `configure'".
  900. `prefix (`Makefile' and `configure')'
  901.      The root of the installation tree.  You can set its `Makefile'
  902.      default with the `--prefix=' command line option to `configure'
  903.      (*note Invoking `configure': Invoking configure.).  The default
  904.      value for `prefix' is `/usr/local'.
  905. `bindir'
  906.      A directory for binary programs that users can run.  The default
  907.      value for `bindir' depends on `prefix'; `bindir' is normally
  908.      changed only indirectly through `prefix'.  The default value for
  909.      `bindir' is `$(prefix)/bin'.
  910. `exec_prefix (`Makefile' and `configure')'
  911.      A directory for host dependent files.  You can specify the
  912.      `Makefile' default value by using the `--exec_prefix=' option to
  913.      `configure'.  (*Note Invoking `configure': Invoking configure.)
  914.      The default value for `exec_prefix' is `$(prefix)'.
  915. `libdir'
  916.      A directory for libraries and support programs.  The default value
  917.      for `libdir' depends on `prefix'; `libdir' is normally changed only
  918.      indirectly through `prefix'.  The default value for `libdir' is
  919.      `$(prefix)/lib'.
  920. `mandir'
  921.      A directory for `man' format documentation ("man pages").  The
  922.      default value for `mandir' depends on `prefix'; `mandir' is
  923.      normally changed only indirectly through `prefix'.  The default
  924.      value for `mandir' is `$(prefix)/man'.
  925. `manNdir'
  926.      These are eight variables named `man1dir', `man2dir', etc.  They
  927.      name the specific directories for each man page section.  For
  928.      example, `man1dir' by default holds the filename `$(mandir)/man1';
  929.      this directory contains `emacs.1' (the man page for GNU Emacs).
  930.      Similarly, `man5dir' contains the value `$(mandir)/man5',
  931.      indicating the directory which holds `rcsfile.5' (the man page
  932.      describing the `rcs' data file format).  The default value for any
  933.      of the `manNdir' variables depends indirectly on `prefix', and is
  934.      normally changed only through `prefix'.  The default value for
  935.      `manNdir' is `$(mandir)/manN'.
  936. `manNext'
  937.      *Not supported by Cygnus `configure'*.  The `GNU Coding Standards'
  938.      do not call for `man1ext', `man2ext', so the intended use for
  939.      `manext' is apparently not parallel to `mandir'.  Its use is not
  940.      clear.  (See also *Note Extensions to the GNU coding standards:
  941.      Makefile extensions.)
  942. `infodir'
  943.      A directory for `info' format documentation.  The default value for
  944.      `infodir' depends indirectly on `prefix'; `infodir' is normally
  945.      changed only through `prefix'.  The default value for `infodir' is
  946.      `$(prefix)/info'.
  947. `docdir'
  948.      A directory for any documentation that is in a format other than
  949.      those used by `info' or `man'.  The default value for `docdir'
  950.      depends indirectly on `prefix'; `docdir' is normally changed only
  951.      through `prefix'.  The default value for `docdir' is
  952.      `$(datadir)/doc'.  *This variable is an extension to the GNU
  953.      coding standards*.  (See also *Note Extensions to the GNU coding
  954.      standards: Makefile extensions.)
  955. `includedir'
  956.      A directory for the header files accompanying the libraries
  957.      installed in `libdir'.  The default value for `includedir' depends
  958.      on `prefix'; `includedir' is normally changed only indirectly
  959.      through `prefix'.  The default value for `includedir' is
  960.      `$(prefix)/include'.
  961. File: configure.info,  Node: Host,  Next: Target,  Prev: Install locations,  Up: Using configure
  962.    The arguments to `configure' are "hosts".  By "host" we mean the
  963. "environment" in which the source will be compiled.  This need not
  964. necessarily be the same as the physical machine involved, although it
  965. usually is.
  966.    For example, if some obscure machine had the GNU `POSIX' emulation
  967. libraries available, it would be possible to configure most GNU source
  968. for a `POSIX' system and build it on the obscure host.
  969.    For more on this topic, see *Note On Configuring Development Tools:
  970. (cfg-paper)Host Environments.
  971. File: configure.info,  Node: Target,  Next: Makefile fragments,  Prev: Host,  Up: Using configure
  972. Target
  973. ======
  974.    For building native development tools, or most of the other GNU
  975. tools, you need not worry about the target.  The "target" of a
  976. configuration defaults to the same as the "host".
  977.    For building cross development tools, please see *Note On
  978. Configuring Development Tools: (cfg-paper)Building Development
  979. Environments.
  980. This is Info file configure.info, produced by Makeinfo-1.55 from the
  981. input file configure.texi.
  982. START-INFO-DIR-ENTRY
  983. * configure: (configure).        Cygnus configure.
  984. END-INFO-DIR-ENTRY
  985.    This document describes the Cygnus Support version of `configure'.
  986.    Copyright (C) 1991, 1992, 1993 Cygnus Support Permission is granted
  987. to make and distribute verbatim copies of this manual provided the
  988. copyright notice and this permission notice are preserved on all copies.
  989.    Permission is granted to copy and distribute modified versions of
  990. this manual under the conditions for verbatim copying, provided that
  991. the entire resulting derived work is distributed under the terms of a
  992. permission notice identical to this one.
  993.    Permission is granted to copy and distribute translations of this
  994. manual into another language, under the above conditions for modified
  995. versions, except that this permission notice may be stated in a
  996. translation approved by Cygnus Support.
  997. File: configure.info,  Node: Makefile fragments,  Next: Makefile extensions,  Prev: Target,  Up: Using configure
  998. Adding information about local conventions
  999. ==========================================
  1000.    If you find that a tool does not get configured to your liking, or if
  1001. `configure''s conventions differ from your local conventions, you should
  1002. probably consider "site-specific `Makefile' fragments".  See also *Note
  1003. Adding site info: Sites.
  1004.    These are probably not the right choice for options that can be set
  1005. from the `configure' command line or for differences that are host or
  1006. target dependent.
  1007.    Cygnus `configure' uses three types of `Makefile' fragments.  In a
  1008. generated `Makefile' they appear in the order: "target fragment", "host
  1009. fragment", and "site fragment".  This allows host fragments to override
  1010. target fragments, and site fragments to override both.
  1011.    Host-specific `Makefile' fragments conventionally reside in the
  1012. `./config/' subdirectory with names of the form `mh-HOST'.  They are
  1013. used for hosts that require odd options to the standard compiler and
  1014. for compile time options based on the host configuration.
  1015.    Target-specific `Makefile' fragments conventionally reside in the
  1016. `./config/' subdirectory with names of the form `mt-TARGET'.  They are
  1017. used for target dependent compile time options.
  1018.    Site specific `Makefile' fragments conventionally reside in the
  1019. `./config/' subdirectory with names of the form `ms-SITE'.  They are
  1020. used to override host- and target-independent compile time options.
  1021. Note that you can also override these options on the `make' invocation
  1022. line.
  1023. File: configure.info,  Node: Makefile extensions,  Prev: Makefile fragments,  Up: Using configure
  1024. Extensions to the GNU coding standards
  1025. ======================================
  1026.    The following additions to the GNU coding standards are required for
  1027. Cygnus `configure' to work properly.
  1028.    * The `Makefile' must contain exactly one line starting with `####'.
  1029.      This line should follow any default macro definitions but precede
  1030.      any rules.  Host, target, and site-specific `Makefile' fragments
  1031.      will be inserted immediately after this line.  If the line is
  1032.      missing, the fragments will not be inserted.
  1033.    * Cygnus adds the following targets to each `Makefile'.  Their
  1034.      existence is not required for Cygnus `configure', but they are
  1035.      documented here for completeness.
  1036.     `info'
  1037.           Build all info files from texinfo source.
  1038.     `install-info'
  1039.           Install all info files.
  1040.     `clean-info'
  1041.           Remove all info files and any intermediate files that can be
  1042.           generated from texinfo source.
  1043.     `Makefile'
  1044.           Calls `./config.status' to rebuild the `Makefile' in this
  1045.           directory.
  1046.    * The following `Makefile' targets have revised semantics:
  1047.     `install'
  1048.           Should *not* depend on the target `all'.  If the program is
  1049.           not already built, `make install' should fail.  This allows
  1050.           you to install programs even when `make' would otherwise
  1051.           determine them to be out of date.  This can happen, for
  1052.           example, when the result of a `make all' is transported via
  1053.           tape to another machine for installation.
  1054.     `clean'
  1055.           Should remove any file that can be regenerated by the
  1056.           `Makefile', excepting only the `Makefile' itself, and any
  1057.           links created by `configure'.  That is, `make all clean'
  1058.           should return all directories to their original condition.
  1059.           If this is not done, then the command sequence
  1060.                configure HOST1 ; make all install clean ;
  1061.                configure HOST2 ; make all install
  1062.           will fail because of intermediate files intended for HOST1.
  1063.    * Cygnus adds the following macros to all `Makefile.in' files, but
  1064.      you are not required to use them to run Cygnus `configure'.
  1065.     `docdir'
  1066.           The directory in which to install any documentation that is
  1067.           not either a `man' page or an `info' file.  For `man' pages,
  1068.           see `mandir'; for `info', see `infodir'.
  1069.     `includedir'
  1070.           The directory in which to install any header files that
  1071.           should be made available to users.  This is distinct from the
  1072.           `gcc' include directory, which is intended for `gcc' only.
  1073.           Files in `includedir' may be used by `cc' as well.
  1074.    * The following macros have revised semantics.  Most of them describe
  1075.      installation directories; see also *Note Full description of all
  1076.      installation subdirectories: Install details.
  1077.     `datadir'
  1078.           is used for host independent data files.
  1079.     `mandir'
  1080.           The default path for `mandir' depends on `prefix'.
  1081.     `infodir'
  1082.           The default path for `infodir' depends on `prefix'.
  1083.     `BISON'
  1084.           is assumed to have a `yacc' calling convention.  To use GNU
  1085.           `bison', use `BISON=bison -y'.
  1086.    * Each Cygnus `Makefile' also conforms to one additional restriction:
  1087.      When libraries are installed, the line containing the call to
  1088.      `INSTALL_DATA' should always be followed by a line containing a
  1089.      call to `RANLIB' on the installed library.  This is to accommodate
  1090.      systems that use `ranlib'.  Systems that do not use `ranlib' can
  1091.      set `RANLIB' to "`echo'" in a host specific `Makefile' fragment.
  1092. File: configure.info,  Node: Porting,  Next: Variables Index,  Prev: Using configure,  Up: Top
  1093. Porting with `configure'
  1094. ************************
  1095.    This section explains how to add programs, host and target
  1096. configuration names, and site-specific information to Cygnus
  1097. `configure'.
  1098. * Menu:
  1099. * Programs::               Adding configure to new programs
  1100. * Hosts and targets::      Adding hosts and targets
  1101. * Sites::                  Adding site info
  1102. File: configure.info,  Node: Programs,  Next: Hosts and targets,  Up: Porting
  1103. Adding `configure' to new programs
  1104. ==================================
  1105.    If you are writing a new program, you probably shouldn't worry about
  1106. porting or configuration issues until it is running reasonably on some
  1107. host.  Then refer back to this section.
  1108.    If your program currently has a `configure' script that meets the GNU
  1109. standards (*note How Configuration Should Work:
  1110. (standards)Configuration., please do not add Cygnus `configure'.  It
  1111. should be possible to add this program without change to a Cygnus
  1112. `configure' style source tree.
  1113.    If the program is not target dependent, please consider using
  1114. `autoconf' instead of Cygnus `configure'.  `autoconf' is available from
  1115. the Free Software Foundation; it is a program which generates an
  1116. executable shell script called `configure' by automatically finding
  1117. information on the system to be configured on and embedding this
  1118. information in the shell script.  `configure' scripts generated by
  1119. `autoconf' require no arguments, and accept the same options as Cygnus
  1120. `configure'.  For detailed instructions on using `autoconf', see *Note
  1121. How to organize and produce Autoconf scripts: (autoconf)Making
  1122. configure Scripts.
  1123.    To add Cygnus `configure' to an existing program, do the following:
  1124. *Make sure the `Makefile' conforms to the GNU standard
  1125.      The coding standard for writing a GNU `Makefile' is described in
  1126.      *Note Makefile Conventions: (standards)Makefiles.  For technical
  1127.      information on writing a `Makefile', see *Note Writing Makefiles:
  1128.      (make)Makefiles.
  1129. *Add Cygnus extensions to the `Makefile'
  1130.      These are described in *Note Extensions to the GNU coding
  1131.      standards: Makefile extensions.
  1132. *Collect package specific definitions in a single file
  1133.      Many packages are best configured using a common `Makefile'
  1134.      fragment which is included by all of the makefiles in the
  1135.      different directories of the package.  In order to accomplish
  1136.      this, set the variable `package_makefile_fragment' to the name of
  1137.      the file.  It will be inserted into the final `Makefile' before
  1138.      the target-specific fragment.
  1139. *Move host support from `Makefile' to fragments
  1140.      This usually involves finding sections of the `Makefile' that say
  1141.      things like "uncomment these lines for host HOST" and moving them
  1142.      to a new file called `./config/mh-HOST'. For more information, see
  1143.      *Note Adding hosts and targets: Hosts and targets.
  1144. *Choose defaults
  1145.      If the program has compile-time options that determine the way the
  1146.      program should behave, choose reasonable defaults and make these
  1147.      `Makefile' variables.  Be sure the variables are assigned their
  1148.      default values before the `####' line so that site-specific
  1149.      `Makefile' fragments can override them (*note Extensions to the
  1150.      GNU coding standards: Makefile extensions.).
  1151. *Locate configuration files
  1152.      If there is configuration information in header files or source
  1153.      files, separate it in such a way that the files have generic
  1154.      names.  Then move the specific instances of those files into the
  1155.      `./config/' subdirectory.
  1156. *Separate host and target information
  1157.      Some programs already have this information separated.  If yours
  1158.      does not, you will need to separate these two kinds of
  1159.      configuration information.  "Host specific" information is the
  1160.      information needed to compile the program.  "Target specific"
  1161.      information is information on the format of data files that the
  1162.      program will read or write.  This information should live in
  1163.      separate files in the `./config/' subdirectory with names that
  1164.      reflect the configuration for which they are intended.
  1165.      At this point you might skip this step and simply move on.  If you
  1166.      do, you should end up with a program that can be configured only
  1167.      to build "native" tools, that is, tools for which the host system
  1168.      is also the target system.  Later, you could attempt to build a
  1169.      cross tool and separate out the target-specific information by
  1170.      figuring out what went wrong.  This is often simpler than combing
  1171.      through all of the source code.
  1172. *Write `configure.in'
  1173.      Usually this involves writing shell script fragments to map from
  1174.      canonical configuration names into the names of the configuration
  1175.      files.  These files will then be linked at configure time from the
  1176.      specific instances of those files in `./config' to files in the
  1177.      build directory with more generic names.  (See also *Note Build
  1178.      directories: Build directories.)  The format of `configure.in' is
  1179.      described in *Note The `configure.in' input file: configure.in.
  1180. *Rename `Makefile' to `Makefile.in'
  1181.    At this point you should have a program that can be configured using
  1182. Cygnus `configure'.
  1183. File: configure.info,  Node: Hosts and targets,  Next: Sites,  Prev: Programs,  Up: Porting
  1184. Adding hosts and targets
  1185. ========================
  1186.    To add a host or target to a program that already uses Cygnus
  1187. `configure', do the following.
  1188.    * Make sure the new configuration name is represented in
  1189.      `config.sub'.  If not, add it.  For more details, see the comments
  1190.      in the shell script `config.sub'.
  1191.    * If you are adding a host configuration, look in `configure.in', in
  1192.      the "per-host" section.  Make sure that your configuration name is
  1193.      represented in the mapping from host configuration names to
  1194.      configuration files.  If not, add it.  Also see *Note The
  1195.      `configure.in' input file: configure.in.
  1196.    * If you are adding a target configuration, look in `configure.in',
  1197.      in the "per-target" section.  Make sure that your configuration
  1198.      name is represented in the mapping from target configuration names
  1199.      to configuration files.  If not, add it.  Also see *Note The
  1200.      `configure.in' input file: configure.in.
  1201.    * Look in `configure.in' for the variables `files', `links',
  1202.      `host_makefile_frag', and `target_makefile_frag'.  The values
  1203.      assigned to these variables are the names of the configuration
  1204.      files, (relative to `srcdir') that the program uses.  Make sure
  1205.      that copies of the files exist for your host.  If not, create
  1206.      them.  See also *Note Variables available to `configure.in':
  1207.      configure variables.
  1208.    This should be enough to `configure' for a new host or target
  1209. configuration name.  Getting the program to compile and run properly
  1210. represents the hardest work of any port.
  1211. File: configure.info,  Node: Sites,  Prev: Hosts and targets,  Up: Porting
  1212. Adding site info
  1213. ================
  1214.    If some of the `Makefile' defaults are not right for your site, you
  1215. can build site-specific `Makefile' fragments.  To do this, do the
  1216. following.
  1217.    * Choose a name for your site.  It must currently be less than
  1218.      eleven characters.
  1219.    * If the program source does not have a `./config/' subdirectory,
  1220.      create it.
  1221.    * Create a file called `./config/ms-SITE' where SITE is the name of
  1222.      your site.  In it, set whatever `Makefile' variables you need to
  1223.      override to match your site's conventions.
  1224.    * Configure the program with:
  1225.           configure ... --site=SITE
  1226. File: configure.info,  Node: Variables Index,  Next: Concept Index,  Prev: Porting,  Up: Top
  1227. Variable Index
  1228. **************
  1229. * Menu:
  1230. * bindir:                               Install details.
  1231. * configdirs:                           configure variables.
  1232. * docdir:                               Install details.
  1233. * exec_prefix:                          Install details.
  1234. * exec_prefix:                          Invoking configure.
  1235. * exec_prefix:                          exec_prefix.
  1236. * files:                                configure variables.
  1237. * floating_point:                       configure variables.
  1238. * gas:                                  configure variables.
  1239. * host:                                 configure variables.
  1240. * host_cpu:                             configure variables.
  1241. * host_makefile_frag:                   configure variables.
  1242. * host_os:                              configure variables.
  1243. * host_vendor:                          configure variables.
  1244. * includedir:                           Install details.
  1245. * infodir:                              Install details.
  1246. * libdir:                               Install details.
  1247. * links:                                configure variables.
  1248. * Makefile:                             configure variables.
  1249. * manNdir:                              Install details.
  1250. * manNext:                              Install details.
  1251. * mandir:                               Install details.
  1252. * nfp:                                  Invoking configure.
  1253. * norecursion:                          Invoking configure.
  1254. * package_makefile_frag:                configure variables.
  1255. * prefix:                               Invoking configure.
  1256. * prefix:                               Install details.
  1257. * prefix:                               prefix.
  1258. * program_prefix:                       Invoking configure.
  1259. * removing:                             configure variables.
  1260. * rm:                                   Invoking configure.
  1261. * site:                                 Invoking configure.
  1262. * site_makefile_frag:                   configure variables.
  1263. * srcdir:                               configure variables.
  1264. * srcdir:                               What configure does.
  1265. * srcdir:                               Invoking configure.
  1266. * srcname:                              configure variables.
  1267. * srctrigger:                           configure variables.
  1268. * subdirs:                              configure variables.
  1269. * target:                               Invoking configure.
  1270. * target:                               configure variables.
  1271. * target_cpu:                           configure variables.
  1272. * target_makefile_frag:                 configure variables.
  1273. * target_os:                            configure variables.
  1274. * target_vendor:                        configure variables.
  1275. * tmpdir:                               Invoking configure.
  1276. * verbose:                              Invoking configure.
  1277. * with-PACKAGE:                         Invoking configure.
  1278. File: configure.info,  Node: Concept Index,  Prev: Variables Index,  Up: Top
  1279. Concept Index
  1280. *************
  1281. * Menu:
  1282. * -exec_prefix:                         Invoking configure.
  1283. * -help:                                Invoking configure.
  1284. * -nfp:                                 Invoking configure.
  1285. * -norecursion:                         Invoking configure.
  1286. * -prefix:                              Invoking configure.
  1287. * -program_prefix:                      Invoking configure.
  1288. * -rm:                                  Invoking configure.
  1289. * -site:                                Invoking configure.
  1290. * -srcdir:                              Invoking configure.
  1291. * -target:                              Invoking configure.
  1292. * -tmpdir:                              Invoking configure.
  1293. * -version:                             Invoking configure.
  1294. * -with-PACKAGE:                        Invoking configure.
  1295. * -s:                                   Invoking configure.
  1296. * -v:                                   Invoking configure.
  1297. * .gdbinit:                             What configure does.
  1298. * autoconf:                             Programs.
  1299. * bindir:                               Install details.
  1300. * config.guess:                         config.guess.
  1301. * config.guess definition:              What configure really does.
  1302. * config.status:                        What configure does.
  1303. * config.status:                        config.status.
  1304. * config.status definition:             What configure really does.
  1305. * config.sub definition:                What configure really does.
  1306. * config/ subdirectory:                 What configure really does.
  1307. * configdirs:                           configure variables.
  1308. * configure.in:                         configure.in.
  1309. * configure.in definition:              What configure really does.
  1310. * configure back end:                   What configure really does.
  1311. * configure details:                    What configure really does.
  1312. * docdir:                               Install details.
  1313. * exec_prefix:                          Install details.
  1314. * exec_prefix option:                   Invoking configure.
  1315. * floating_point:                       configure variables.
  1316. * help option:                          Invoking configure.
  1317. * host:                                 configure variables.
  1318. * includedir:                           Install details.
  1319. * infodir:                              Install details.
  1320. * libdir:                               Install details.
  1321. * Makefile.in definition:               What configure really does.
  1322. * Makefile extensions:                  Makefile extensions.
  1323. * Makefile fragments:                   Makefile fragments.
  1324. * Makefile generation:                  Makefile generation.
  1325. * Makefile generation:                  What configure does.
  1326. * manNdir:                              Install details.
  1327. * manNext:                              Install details.
  1328. * mandir:                               Install details.
  1329. * nfp option:                           configure variables.
  1330. * nfp option:                           Invoking configure.
  1331. * norecursion option:                   Invoking configure.
  1332. * prefix:                               Install details.
  1333. * prefix option:                        Invoking configure.
  1334. * prefix option:                        prefix.
  1335. * program_prefix option:                Invoking configure.
  1336. * rm option:                            configure variables.
  1337. * rm option:                            Invoking configure.
  1338. * site option:                          Invoking configure.
  1339. * srcdir:                               What configure does.
  1340. * srcdir:                               configure variables.
  1341. * srcdir option:                        Invoking configure.
  1342. * srcname:                              configure variables.
  1343. * srctrigger:                           configure variables.
  1344. * subdirs:                              configure variables.
  1345. * s option:                             Invoking configure.
  1346. * target:                               configure variables.
  1347. * target option:                        Invoking configure.
  1348. * tmpdir option:                        Invoking configure.
  1349. * v option:                             Invoking configure.
  1350. * with-PACKAGE option:                  Invoking configure.
  1351. * with-gnu-as option:                   configure variables.
  1352. * configure.in interface:               configure variables.
  1353. * host shell-script fragment:           per-host.
  1354. * per-host section:                     per-host.
  1355. * per-host section:                     configure.in.
  1356. * per-invocation section:               Declarations.
  1357. * per-invocation section:               configure.in.
  1358. * per-target section:                   configure.in.
  1359. * per-target section:                   per-target.
  1360. * post-target section:                  post-target.
  1361. * post-target section:                  configure.in.
  1362. * Abbreviating option names:            Invoking configure.
  1363. * Adding configure to new programs:     Programs.
  1364. * Adding hosts and targets:             Hosts and targets.
  1365. * Adding local info:                    Makefile fragments.
  1366. * Adding site info:                     Makefile fragments.
  1367. * Adding site info:                     Sites.
  1368. * Behind the scenes:                    What configure really does.
  1369. * BISON:                                Makefile extensions.
  1370. * Build directories:                    Build directories.
  1371. * Build directories:                    What configure does.
  1372. * Build variables:                      Build variables.
  1373. * Building for multiple hosts:          Build directories.
  1374. * Building for multiple targets:        Build directories.
  1375. * Canonical "triple":                   configure variables.
  1376. * Canonical "triple":                   configure variables.
  1377. * Changing the install directory:       prefix.
  1378. * clean:                                Makefile extensions.
  1379. * clean-info:                           Makefile extensions.
  1380. * Coding standards extensions:          Makefile extensions.
  1381. * configure variables:                  configure variables.
  1382. * Configuring for multiple hosts:       exec_prefix.
  1383. * Cygnus extensions:                    Makefile extensions.
  1384. * Cygnus Support Developer's Kit:       Build variables.
  1385. * Cygnus Support Developer's Kit:       What configure does.
  1386. * datadir:                              Makefile extensions.
  1387. * Declarations section:                 Declarations.
  1388. * Default configuration:                Makefile generation.
  1389. * Detailed usage:                       Using configure.
  1390. * docdir:                               Makefile extensions.
  1391. * Example configure.in:                 Example.
  1392. * Example session:                      What configure really does.
  1393. * Example session:                      Makefile extensions.
  1394. * Example session:                      Build directories.
  1395. * Example session:                      exec_prefix.
  1396. * Example session:                      Build directories.
  1397. * Example session:                      Build variables.
  1398. * Example session:                      Sites.
  1399. * Example session:                      Invoking configure.
  1400. * Example session:                      Invoking configure.
  1401. * For each invocation:                  Declarations.
  1402. * Host:                                 Host.
  1403. * Host-specific instructions:           per-host.
  1404. * Hosts and targets:                    Hosts and targets.
  1405. * includedir:                           Makefile extensions.
  1406. * info:                                 Makefile extensions.
  1407. * infodir:                              Makefile extensions.
  1408. * install:                              Makefile extensions.
  1409. * Install details:                      Install details.
  1410. * Install locations:                    Install locations.
  1411. * install-info:                         Makefile extensions.
  1412. * Installation subdirectories:          Install details.
  1413. * Installing host-independent files:    exec_prefix.
  1414. * Introduction:                         What configure does.
  1415. * Invoking configure:                   Invoking configure.
  1416. * Local conventions:                    Makefile fragments.
  1417. * Makefile:                             Makefile extensions.
  1418. * mandir:                               Makefile extensions.
  1419. * Minimal configure.in example:         Minimal.
  1420. * Object directories:                   Build directories.
  1421. * Other files:                          What configure really does.
  1422. * Overview:                             What configure does.
  1423. * Porting with configure:               Porting.
  1424. * Post-target shell-script fragment:    post-target.
  1425. * Recursion:                            What configure does.
  1426. * Sample configure.in:                  Example.
  1427. * Sharing host-independent files:       exec_prefix.
  1428. * Sites:                                Sites.
  1429. * Subdirectories:                       Install details.
  1430. * Symbolic links:                       configure variables.
  1431. * Symbolic links:                       configure variables.
  1432. * Symbolic links:                       What configure does.
  1433. * Target:                               Target.
  1434. * target shell-script fragment:         per-target.
  1435. * Target-specific instructions:         per-target.
  1436. * The exec_prefix directory:            exec_prefix.
  1437. * Truncating option names:              Invoking configure.
  1438. * Usage:                                Invoking configure.
  1439. * Usage:                                Invoking configure.
  1440. * Usage: detailed:                      Using configure.
  1441. * Using configure:                      Using configure.
  1442. * Variables:                            Build variables.
  1443. * Verbose Output:                       Invoking configure.
  1444. * version:                              Invoking configure.
  1445. * version:                              Invoking configure.
  1446. * What configure does:                  What configure does.
  1447. * What configure really does:           What configure really does.
  1448. * Where to install:                     Install locations.
  1449.